Capturing real-time user interactions as events gives you actionable insights with click and conversion metrics, and they help you increase your customer engagement and conversions. Events are used to activate Algolia features and products like:

  • NeuralSearch
  • Algolia Recommend
  • Personalization
  • Dynamic Re-Ranking
  • Query Categorization
  • Search analytics
  • Revenue analytics
  • A/B testing.

​
Enable events collection

Set the clickAnalytics parameter to true when making search requests. This includes the queryID parameter in the search response, which is required for linking events and search requests.

JavaScript
    const algoliasearch = require("algoliasearch");
    const client = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");
    const index = client.initIndex("YourIndexName");

    index
    .search("query test", 
+     { clickAnalytics: true }
    ).then(({ queryID, hits }) => {
        console.log(hits);
        console.log(queryID);
    });

​
Initialize search-insights.js

Install the search-insights library.

<script>
    var ALGOLIA_INSIGHTS_SRC =
    "https://cdn.jsdelivr.net/npm/search-insights@2.16.3/dist/search-insights.min.js";
    !function(e,a,t,n,s,i,c)
    {
    ((e.AlgoliaAnalyticsObject = s),
    (e[s] =
        e[s] ||
        function () {
        (e[s].queue = e[s].queue || []).push(arguments);
        }),
    (e[s].version = (n.match(/@([^\/]+)\/?/) || [])[1]),
    (i = a.createElement(t)),
    (c = a.getElementsByTagName(t)[0]),
    (i.async = 1),
    (i.src = n),
    c.parentNode.insertBefore(i, c))
    }
    (window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");
</script>

After installing the search-insights library, initialize the client in your website.

JavaScript
import aa from 'search-insights';

aa("init", {
appId: "YourApplicationID",
apiKey: "YourSearchOnlyAPIKey",
});

​
Understand which events to track

To understand which events you should send, think about the different steps a user takes through your website to reach the final goal: the product purchase.

Starting with a search on any of your pages, a user might take the following actions:

  1. Select a product from the search results to open the product details page.
  2. Add a product to the shopping cart.
  3. Buy the product.

​
Search and search results pages

User actionMethod name
User clicks search resultclickedObjectIDsAfterSearch
User adds product to shopping cartaddedToCartObjectIDsAfterSearch
User clicks categories/filtersclickedFilters
User views search resultsviewedObjectIDs

​
Product listing and category pages

User actionMethod name
User clicks productclickedObjectIDsAfterSearch
User adds product to shopping cartaddedToCartObjectIDsAfterSearch
User views category pageviewedObjectIDs

​
Product details page

User actionMethod name
User adds product to cartaddedToCartObjectIDsAfterSearch
User views productviewedObjectIDs

​
Checkout page

User actionMethod name
User buys productpurchasedObjectIDsAfterSearch

​
Keep track of query IDs

Conversion events are often triggered outside of the search results page. In order to correctly attribute which query is responsible for a conversion, it is necessary to keep track of the query ID returned when a search is performed so that it can be included in conversion events.

To relate the conversion events back to the search request made on your search results or category pages, you need to keep track of the query IDs across your pages.

​
Track click events

To send click events with the Insights client, add the following code whenever a user clicks on a product.

JavaScript
aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Product Clicked",
  objectIDs: ["objectID-1"],
});

If you want to track clicks on search results pages, add the following code whenever a user clicks on a product.

JavaScript
aa("clickedObjectIDsAfterSearch", {
  index: "YourIndexName",
  queryID: "YourQueryID", // From the search response
  eventName: "Product Clicked",
  objectIDs: ["objectID-1"],
  positions: [1],
});
  • The objectID is included in the search response for each search result as part of the hits attribute.
  • The positions array in clickedObjectIdsAfterSearch contains a one-based index of the product hit in the search results.

​
Track add-to-cart events

Add the following code to all components and pages where users can add products to their shopping cart.

JavaScript
aa("addedToCartObjectIDsAfterSearch", {
  eventName: "Product Added To Cart",
  index: "YourIndexName",
  objectIDs: ["objectID-1"],
  objectData: [
    {
      queryID: "queryID-1",
      price: 19.99,
      discount: 3.99,
      quantity: 3,
    },
  ],
  currency: "USD",
});

The objectID is included in the search response for each search result as part of the hits attribute.

You should store the query ID with other product details when updating a user’s shopping cart. This makes it easy to record query IDs for each item for any following purchase events.

​
Track purchase events

To record when a user completes a purchase, add the following code:

JavaScript
aa("purchasedObjectIDsAfterSearch", {
  eventName: "Products Purchased",
  index: "YourIndexName",
  objectIDs: ["objectID-1", "objectID-2"],
  objectData: [
    {
      queryID: "queryID-1",
      price: 19.99,
      discount: 3.99,
      quantity: 3,
    },
    {
      queryID: "queryID-2",
      price: 59.99,
      quantity: 2,
    },
  ],
  currency: "USD",
});

Use objectData to record per-object data, such as the price and quantity of the purchased products.

Users often purchase items that were added to the cart in response to different queries. For example, a user might search for “shoes” and add a pair of shoes to their cart. Then, they search for “lamp” and add a lamp to their cart. Then, they check out and complete the purchase of both items. In this case, there would be a single purchase event. Each item---the shoes and the lamp---will have the query ID of the search they originated from.

​
(Optional) Handle known users for Personalization

For effective personalization, you need to identify users across sessions. It’s best to use an identifier from your authentication, user profile, or ecommerce service after users signed in.

After getting the identifier from your system, set it as authenticatedUserToken parameter.

JavaScript
// Get a unique, pseudonymous identifier for signed-in users
const authenticatedUserToken = getUserTokenAfterSignIn();
window.aa("setAuthenticatedUserToken", authenticatedUserToken);

When you set the authenticatedUserToken parameter in the Insights client, you also need to update the user token you send with your search requests.

JavaScript
function getEffectiveUserToken() {
    const userToken = window.aa("getUserToken");
    const authenticatedUserToken = window.aa("getAuthenticatedUserToken");
    return authenticatedUserToken || userToken;
}

index.search("query", {
    clickAnalytics: true,
    userToken: getEffectiveUserToken(),
}).then(({queryID, hits}) => {
    console.log(hits);
    console.log(queryID);
})

If you can’t get persistent user identifiers from your system, you can store the anonymous user token in a cookie after obtaining user consent.

JavaScript
// If user consented
aa("init", {
    partial: true,
    useCookies: true,
});

For more information, see User token.

​
(Optional) Send view events for Personalization

Personalization benefits from the same click and conversion events, plus it can use view events to enrich user profiles.

To capture view events, such as when a user views search results, add this code:

JavaScript
window.aa("viewedObjectIDs", {
    index: "YourIndexName",
    eventName: "Product Viewed",
    objectIDs: ["objectID-1"],
});